MacWorld 1999 July/Macworld (1999-07).dmg/Shareware World/Info/For Developers/Mops 3.4.sea/Quick Edit ƒ/Quick Edit 3.0 ReadMe

Text File | 1998-09-26 | 28KB | 591 lines

  \ 26Sep98 DBH

IMPORTANT TIP ABOUT READING THIS FILE:  While holding down the ctrl key, click
the mouse anywhere in the window and a popup menu will appear.  The popup menu
is an index into this ReadMe file.  By selecting from the menu you can quickly
jump to various parts of this file.  You must, of course, be using Quick Edit
to read this file.




This information has been updated for version 3.0

:class WHAT THIS IS ****

Quick Edit (QE) is a programmer's source code editor intended for use with
Mops, Michael's Object Oriented Programming System, and System 7. Typed Mops
commands can be executed directly from an editor window, thus avoiding
copy-switch-paste.  There is a lot more interaction between Mops and QE.
Mops and QE work together to form an Integrated Development Environment.

Also included are a set of text files that comprise a Subject Sorted
Glossary for Mops definitions.


:class NEW FOR VERSION 3.0 ****

QE 3.0 is a "maintenance" version.  No radically new features have been
added.  A few problems have been cleaned up.  Existing features have been
polished a bit.  Most importantly, QE is now compatible with Power Mops.

•    QE will now recognize either Power Mops or the 68K Mops when sending
    AppleEvents.

•    The popup method browser now shows "code" methods.  This was a bug.

•    The popup method browser now displays everything in alphabetic order.

•    Clicking in the lower left box will toggle the wordwrap or console
    features.

•    Sometimes when printing, the first 2 lines overlapped somewhat.  This has
    been fixed.

•    Shift-Return is now the same as Enter.  This was a request from a user.

•    Corrected some Glossary and Subject definitions.

•    The default setting for "Whole Word Search" in the Find... Dialog is
    now user settable with the QEF1 resource number 9  (00 01 = on, 00 00 = off)



:class WHAT YOU NEED TO USE QUICK EDIT ****

1) System 7.x

2) Mops (Michael's Object Oriented Programming System version 3.x).

3) The provided Mops Glossary file.

4) I strongly recommend that you also use (load) the provided file "QEconsole"
and turn on the Edit/Console feature for at least one of your open QE windows.


Actually, 1) and 2) are not absolutely required as Quick Edit will function
quite well as a stand-alone text processor without System 7 or Mops.  In that
case you don't need 3) or 4) either.


:class HOW TO USE QUICK EDIT ****

1) Launch Quick Edit and use it to change your Mops.paths file (in folder
Mopsƒ) to include any folders that you wish to contain Mops source code.  If
you are unsure about how to do this, just save any newly created Mops source
code (files you create with QE) in the folder Mopsƒ for now.

2) Launch Mops.

3) Load the provided file, QEconsole, into Mops.  Save your new Mops dictionary
as, e.g., MopsQE.dic  (this step is not necessary, but is recommended).  Turn
on the Edit/Console feature using the menu from within Quick Edit.  The word
"console" will appear in the bottom left of the window.

4) Now you should be able to execute typed Mops instructions from a QE window
as if you were typing into the Mops window and any textual output, including
stack items, will appear in your QE console window instead of the Mops console
window.  See the Console feature.  Remember that you must use the enter key,
not the return key, to execute commands.


:class CONSOLE

:m Console  A QE window can now become a front end for Mops.  All textual input
*and* output is performed completely from within QE.  First, the file
"QEconsole", provided with this release, must be loaded into Mops.  Then, by
toggling the menu item Edit/Console, you can declare the current QE window to
be a console window.  The word "Console" will appear in the lower left corner
of the window.  Other windows will be unaffected.  I strongly suggest that you
try this.  More details are provided later in this file.  You can also toggle
the console feature by clicking the mouse on the spot in the window where the
word "Console" appears when turned on.


:m > prompt  After pressing enter from a console window you will get a ">"
prompt from Mops, followed by any stack items that may be present.  For
example:

3 4 <enter>
>3 4

You can still enter Mops commands from non-console windows, but any output will
appear in the Mops console instead of the current QE window.  This behavior is
desirable for source code files that you don't want to become "littered" with
output from Mops.  Of course, you can declare any window or file in QE to be a
console window if you wish.  I typically leave my source code windows as
non-console, and have one untitled window as a console.

You must still switch over to Mops in order to perform user interface actions.
But I think you will find that a QE console window can greatly enhance your
development productivity because all of the QE programmer support features are
immediately available:  Glossary, Open Source, Edit File, Save&Load, etc.

If you get an error message, such as when trying to execute an undefined Mops
word, you may see something like the following:

foo <enter>

undefined word
>QECONS foo
           ^
Don't worry about the presence of >QECONS ( or NEWVECS ).  These commands are
being sent by QE to Mops each time an AppleEvent is sent.  The purpose is to
reset the Mops output vecs each time because Mops does not know what kind of QE
window, console or non-console, is currently in use.  See the file "QEconsole"
for exact details of what is going on if you are interested.


:class MOPS GLOSSARY ****

***IMPORTANT***
You must keep the file "Mops Glossary" in the same folder as Quick Edit.

While using QE it is possible to summon the glossary to look up a definition in
either of 2 ways.  First, you may highlight a word in a QE window and then
invoke the Mops/Glossary menu command (or command-Y).  If you do not highlight
a word, then the first word to the left of the cursor will will be used as the
search word.  Or, if you simply placed the cursor in the middle of a word, then
that word will be used.  If found in the glossary, the word and its definition
will appear in a special window.  A second way to use the glossary is to just
invoke the Mops/Glossary menu command and then begin typing the word that you
wish to look up.  MacForth users will recognize this as the Online Glossary
feature from the Sibley Editor.

If no QE window is open, then the Glossary feature will be unavailable.

You may copy text from the Glossary.   For each definition in the Glossary we
have the stack effect immediately to the right of the name.  Further to the
right, on the same line, we have the Subject Name and File Name (the name of
the Mops file that contains the source code for the word) in
SubjectName/FileName format.

We have included a file, Stack Notation, to define the stack effect
notation used here.

For most subjects we have a Subject Glossary file in the folder Subject
Glossary.  In these files you will find all related words grouped together
in a logical manner by function, rather than by ASCII order.  I find
that printing all of the Subject Glossary files and placing them in a
hole-punch binder with index tabs is an excellent way to keep a quick
reference.  You can also print the ASCII sorted glossary if you want, it's just
a text file, but it is really intended for interactive use within QE.   From
the Glossary you can obtain the source file name, see where the source file is
located from the Mops File Index, and then open the source file to see the
actual definition.  Note that one can now easily open the source for already
compiled code simply by highlighting a word in QE and invoking the Mops/Open
Source menu command (command-=), as long as Mops itself is also running.
You may delete and add to the glossary yourself, but only if you open
the file "Mops Glossary" as a normal edit file, not as it is opened
as the QE glossary window.  Added definitions MUST be in ASCII order
and begin in the first column on a new line.  Only definition names may
begin in the first column.

:class BROWSING MOPS DEFINITIONS AND FILES ****

Particularly convenient is the ability to quickly "browse" Mops definitions and
source files from within Quick Edit while Mops is also running.  By selecting a
Mops word or Mops source file name, you can have the file containing the
definition of that Mops word, or simply the named file, opened into QE with the
menu commands Mops/Open Source and Mops/Edit File.  If you do not highlight a
word, then the first word to the left of the cursor will will be used as the
lookup word or file name.  I highly recommend that you try this, I use it all
the time.  Note that it is not necessary for a file to be loaded in order to
summon it via Edit File, but the file must be in the path specified by your
Mops.paths file.  Also note that module source files can be opened by just
selecting the module name, you do not have to select the actual module source
file name which will have ".txt" appended, although you still could.

Not all Mops definitions can be browsed this way.  Definitions that occur prior
to a file lookup utility, such as all Nucleus definitions (in source files
Nuc1.asm, Nuc2.asm, etc.), cannot be looked up with the Mops/Open Source
command.  In fact, an attempt to do so will result in no response at all.  If
this happens to you, you should next try invoking the Mops/Glossary command and
you should see the definition of the word there (and the Glossary definition
will confirm that this is a nucleus definition).

:m Popup Browser  As before, holding down the ctrl key while clicking the mouse
anywhere in the window will cause a popup menu to appear.  The popup is an
index into any class and method definitions in the current window.  New for QE
2.7 is a similar popup for normal Forth colon definitions.  Press
ctrl-option-click to summon it.  By selecting from the menu you can quickly
jump to various parts of the file.


:class SUBJECT GLOSSARY ****

 ***IMPORTANT***
You must keep the folder "Subject Glossary" in the same folder as Quick Edit.

We have included a set of normal text files that comprise a "Subject Sorted
Glossary".  The purpose of these files is to allow the programmer to quickly
review the available word set for a given category of words.  This avoids
having to read the entire Glossary (which is ascii sorted) in order to find
out what is available.

You can directly open any of these files via menu access to the Subject
(sorted) Glossary.  Under the Mops menu.

:m Custom Subject Menu  The Subject Glossary now has its own menu.  The menu
items are the file names of the corresponding files in the Subject Glossary
folder.  You can customize this menu simply by adding or deleting to the menu
resource of QE.  If you add new file names to the subject menu then you must
also provide the file with the *same* name in the Subject Glossary folder.
Alphabetic order is not a requirement.  You must not rename or move the Subject
Glossary folder.

:class TIPS ****

Change the file Mops.paths to include the directory (folder) that your QE files
are in and you will be able to use the QE menu commands Load… and Save&Load

Save&Load is probably the most used command for me.  My typical Mops
programming session goes like this:

• Launch both Mops and QE
• Open or create a source code file, don't declare it as a QE console.
  Actually, you can declare your source file as a console, but when you
  do a Save&Load your window will then become "littered" with file loading
  messages and so forth.  If you place an "ENDLOAD" at the end of you file
  and then make sure to jump the cursor to the end of the file (e.g. command
  option downarrow), then the litter will cause no problems.
• Invoke Save&Load  (command-K), any compilation errors will cause the
  QE window to scroll to the first occurrence of the offending code.  I can
  then edit the mistake and Save&Load again.  This is *very* quick and also offers
  the added protection of saving code to disk before any fatal crashes could occur.
• Interactive testing of small snippets of code are usually done in a QE console window.
• With a console window, I typically don't even bother to arrange the windows so that
  I can also see the Mops console window.  There is no need.
• But with a non-console window I typically keep all of the QE windows in "right half" mode,
  easy to do with the Window/Right Half or Window/All Windows->Right commands.  This way
  I can still execute commands from QE, or use Load... or Save&Load, and see the resulting
  output in Mops (which is visible on the left side of my screen).
• I frequently use the Glossary, source code browser, Edit File command, and popup browser
  in my Mops programming sessions.

Position both the Mops window and your current QE window so both are visible,
unless you are using a QE console window where it is not necessary to see the
Mops console window.

Pressing enter will execute either just the selected range, or if there
is no selection the entire line will be executed.  Multiple lines or an
entire file may be executed this way.

Pressing enter will normally advance the cursor to the end of the next
line.  Hold down the option key to keep the cursor on the same line.


:class ABOUT QUICK EDIT ****

Quick Edit is written in MacForth and is, for the large part, the
MacForth text editor, or Sibley Editor, with extensions to use Apple Events
for Mops communication.  I also added my favorite tweaks to the editor.
Actually, especially now with version 2.7, the source code for QE is bearing
less and less resemblance to MacForth.  For example, thanks to MacForth's
separated headers and flexible vocabulary management, I have been able to
rename even MacForth kernel words to names that make more sense to me.  For
example, words that simply invoke a toolbox call are now named the same as the
toolbox call.  The Basic text engine is MacForth's, as is a lot of the
difficult file handling stuff.  Kudos to the guys that created this stuff which
include Dave Sibley, Ward McFarland, Xan Gregg, and a few others.

You MacForthers may be interested in knowing that Quick Edit duals as my
MacForth programming environment (as a snapshot, not a turnkey).  No surprise.
There is a global switch that is used to change from QE-as-Mops-editor to
QE-as-MacForth.  All of the programmer's assist features are available in
either mode and behave the same in either mode, except in a different context.
In fact, with the new console feature it is easy to forget which environment
one is using (so I keep a bold "M" or "Q" in the lower left of each window as a
reminder, during development only).

QE behaves mostly in the standard Macintosh manner and so should be fairly easy
to learn.

MacForth users will of course feel pretty much at home except for a few
exceptions that are explained later.

I wrote QE as a tool to make it easier for me to use Mops.  If one
has a desire to explore Forth object oriented programming ( FOOP?
Forth++? ), then a look at Mops is a must.  You will likely find that you
will soon stop exploring and begin writing useful code at a very high
level of productivity.


 Doug Hoffman

 565 Countryside Lane
 Oakland, Michigan  48363-1401
 USA




:class DETAILS OF USING QUICK EDIT ****

:m #ofWindows Up to 20 files (windows) can be open at the same time.  The open
QE file names will appear under the Windows menu and will be preceded by
bullets if the files have unsaved changes.

:m Search Shortcuts There are several useful text search shortcuts that bypass
the Find... dialog. Option-Doubleclick on a word to find the first occurrence.
A subsequent Command-G (Find Same) will then find the next occurrence. Any time
a search fails a simple beep will be issued and the cursor will remain where it
last was.  Command-Doubleclick on a word to do a backwards  search (i.e.
attempt to find the first prior occurrence).  Option- Command-Doubleclick on a
word to find the next occurrence.

If the Text Search dialog is summoned (via Command-F or the menu) any
highlighted text will automatically become the "Search for" parameter.  If
no text was highlighted then the prior "Search for" text will remain.

All searches begin at the current selection point and end at the end of
the file.  If the Text Search dialog is used one can also search all files in
the same directory (folder) as the open file.  Holding down the shift key when
either summoning the Text Search dialog or doing a Find Same (Command-G) will
cause the search to be initiated from the beginning of the file.

:m Command-` (Enter Search$) will enter the hilited text as the search string
without summoning the Text Search dialog.  This is useful for "loading" some
text to search for in one window and then moving to another  window to do the
search.  A Command-Shift-G will start the search at the beginning of the file.
This can be handy.  Command-Shift-F will  also start the search at the
beginning of the file, but will summon the Text Search dialog.

A Popup menu is available that will list all classes and their methods
for the current window.  A ctrl-click in a QE window that contains Mops source
code will yield the menu.  The menu selection will cause a jump to the source
code for the class or method.  Ctrl-option-click will give a popup just for
colon definitions.

:m JumpMarks Up to 10 "bookmarks" or jumpmarks can be set by pressing
Command-Shift-J followed by a number (0 through 9).  Note that after invoking
the menu item nothing else can happen until you press a key.  If you don't
press a number key then QE will simply "beep" at you indicating that no
bookmark was set.  One then jumps to these bookmarks by pressing  Command-J
followed by pressing the corresponding single digit number key.  Again, nothing
else can happen until you press a key.  After pressing Command-J, you can
optionally press B, E, or L, to jump to the file Begining, End, or Last
position prior to the last jump.

Modifier keys for cursor movement works as follows:

Option left/right        move cursor one word
Option up/down            move one line
Command left/right        move to beginning or end of line
Command up/down            move to beginning or end of screen or prev/next screen
Command-Option up/down    move to beginning or end of file
Option-Delete            delete previous word
Command-Backspace        delete to beginning of file
Command-Delete            delete to end of file



:m MiniPrint...  is intended for use only with high resolution printers having
scalable fonts such as LaserWriters or the StyleWriter.  MiniPrinting
will print in a very small Helvetica font and allow for a paper savings
of 3-4 to 1 in most cases.  I find this useful for printing drafts
and reducing the quantity of paper used.

If the printed page seems wrong, try using the Page Setup...  command and
select portrait orientation at 100% scale.

:m SmartScrap Note that cutting and pasting will normally delete and add extra
spaces as necessary in a fashion similar to WriteNow.  This feature is only
activated  after text is hilited via a doubleclick and is then cut or copied.
 Text  that is hilited via shift-extension or singleclick-drag will be cut
and pasted in the normal fashion (i.e. no extra spaces will be automatically
added).

:m AutoIndent Also note that indents via tabs or spaces will be repeated on
subsequent lines upon return unless the option key is pressed.  Auto-Indent is
toggled from the menu.

:m Word Delimiters  In most word processors characters such as a period (.) are
treated as a word delimiter.  So doubleclicking something like " this.word " in
most word  processors will only hilite this or word, depending upon where you
first clicked.  Also, in most word processors a whole word search on " this "
will hit on " this.word " and other compounds of " .this.  ".  Since Forth does
not treat a period as a delimiter, I have chosen to have Quick Edit do
likewise.  So a period, and other normal word delimiters are *not* delimiters
in QE.  This behavior may be different from what you are used to.

The Mops menu contains a few handy Mops commands that will clear the stack or
the Mops window.

A multiple line indent/unindent command is also available in the Text menu.


:class DYNAMIC WORD WRAP ****

I must be quite honest here and explain that QE's dynamic wordwrap feature is
still somewhat "under development".  The implementation in QE 2.6 was pretty
buggy and in retrospect should not have been included.  Dynamic wordwrap in 2.7
is improved but as yet imperfect.  It seems to work best for paragraphs that
are not too long (say 10 lines or less).  Beyond that it does not always work
perfectly (but the imperfections are benign).

Also, I should warn that this feature takes a little getting used to.  It is
best to leave it turned off unless you know that you are editing a paragraph
that you want to wrap.  If you forget that it is turned on and you start to
edit some source code you will probably be surprised and annoyed by the
behavior.  However, when used judiciously the dynamic wordwrap can be a useful
feature because you can just type and edit your thoughts without regard to the
current line length.

Note that wrapping the selection or entire file should not cause any problems
for you (those are much easier tasks), so use those commands without concern.

When activated, word wrap will occur as expected, with a couple of unique
characteristics.  One important difference in the way QE wraps text, compared
to conventional word processors, is that carriage returns are still maintained
at the end of each line.  This is done in order to remain compatible with the
programming source code files as they are expected by most programming
languages, including of course Mops.  Another advantage is that QE can remain
very fast while still providing a word wrap function.  If you take a look at
other text processors that word wrap you will notice a considerable slowing
when wrap is turned on for files of any significant size.  QE does not slow
down at all!

Note that QE's word wrap does much more than simply insert a CR
automatically as you type.  QE will look at the paragraph in which the
cursor resides and perform wrapping on the entire paragraph, and only that
paragraph, automatically as you type.  So there is the second important
difference from the norm in QE's word wrap.  Word wrapping will *only*
occur in the current paragraph ( a paragraph in QE is any text that is
delimited by blank lines).  This means that you could turn on word wrap in
the middle of some source code with very long lines and your typed text
would be wrapped while not affecting the rest of the file.  Be careful
though, because if you forget that wordwrap is activated and start typing
in some long source code lines, then those lines will get split up and a
simple undo is not available (although a File/Revert... is a good way to
recover from this if necessary).  WordWrap is activated through the AutoWrap
menu command under the Text menu.  A bold "W" is also placed at the lower left
of the window as a reminder.  You can also toggle wordwrap on and off by
clicking on the spot where the bold "W" appears.  WordWrap only applies to
files that you specify.  WordWrap activation and length is saved with each
file.  You set the wrap length with the Text/Set AutoWrap... menu command.


:class FONTS/PRINTING ****

:m Cancel Printing  You can cancel a print job that is spooling by pressing
command-. (command-period), even though there is no dialog indicating as such.

:m Normal Printing  After receiving comments, it became clear that a normal
sized printing function should be included without having to fuss with the
resources.  So selecting File/Print... will yield a Monaco 9 "large type"
print.  Also, the 2 different forms of miniprinting are now directly available
from the File menu. MiniPrint(1 col)... will yield a 1 column monospaced print
that is fairly condensed.  MiniPrint(2 col)... will yield a 2 column
proportionally spaced print that is the most condensed.


The window and printer font IDs and font sizes are now resources (QEF1) and so
can be changed to suit.  You must use a resource editor.  I know this isn't
very Mac-like, but it was easy to implement (and we're all programmers  here,
right?).

The QEF1 resources affect things as follows:

RESOURCE ID        AFFECTS                        DEFAULT VALUE

1                window font    ID                $00C8    Modified Monaco (MUST be mono-spaced)
2                window font size            $0009

3                miniprint(2col) font ID        $0015    Helvetica
4                miniprint font size            $0007

7                miniprint(1col) font ID        $0016    Courier
8                option miniprint font size  $0007

Note that the window font MUST be mono-spaced.  But this is not a requirement
for the miniprint fonts.  In fact, the Helvetica default miniprint font, which
is proportionally spaced, is used to allow two columns per page due to the
relatively high character linear density.

We use a proper programmer's screen font that clearly distinguishes
characters that are ambiguous with the Monaco font.  Zero(0) vs. capital
"Oh"(O), Capital"I"(I) vs. lowercase "el"(l).

:m MiniPrinting  All miniprinting will yield approximately 104 lines per column
(standard 81/2 x 11 inch paper) on most printers.  Printing will always wrap
long lines.



:class OTHER FEATURES ****

:m Edit File Mops/Edit File (command-E) menu command.  Hilite the name of a
file and then invoke this menu command.  Or simply type the file name and
invoke the menu (the text to the left of the cursor will be automatically
selected).  The file will be opened.  Also works for module filenames without
having to first append ".txt".

• There is now an "AllWindows->Right" Windows menu command.  Useful for getting all
  open editor windows off to one side so the Mops window can be viewed while still
  in Quick Edit.

:m File WordWrap   You can now wordwrap an entire file instantly with the
Text/Wrap File... menu command.  You can also "unwrap" an entire file with the
Text/Unwrap File command.  You may wish to unwrap a file so you can copy and
paste into a word processor that provides conventional "soft" wrapping of text.

:m Detab File  You can now convert all tabs in a file to spaces with the
Text/Detab File menu command.  This will be convenient when, for example,
pasting QE text into another text processor that does not recognize tabs.

:m Magic Copy   What??   Well, I couldn't think of another name for this.  If
you hold the mouse I-beam over a word (don't click there) and invoke Copy via
command-C, then that word will be pasted at the current cursor location.  But
only if nothing was selected.   I find this to be handy when constructing
definitions comprised of long words that are also nearby (a common situation).
This is much quicker and easier than double-clicking, copying, repositioning
the cursor, and finally pasting.  Besides, all a copy would do before, if
nothing was selected that is, was beep.  Surely we must have something more
useful than that...

:m Page ID...  There is now an option to use up to 5 characters as an
additional "ID" for a file.  Use the Edit/Page ID... menu command.  The ID will
appear in the lower left of the window and will be saved with the file.  You
may wonder "What is this for?", which is a valid question.  I use this as an
aid to manage printouts of large projects that consist of many files.  For
example, one could assign numbers, perhaps 10, 20, 30, and so on to each file.
Individual files may require more than one page to print, but the ID numbering
system is a way to keep things in order without having to reprint everything
when only one file has been changed.  This is somewhat reminiscent of the old
Forth blocks files "triad" printing technique.  The MacForth source code for
QE now consists of over 100 files.  I find it useful to organize them this way.
 The page ID will print in the lower right of each printed page.  Normal page
numbering within the file is as always.



:class PACKING LIST ****

The following is a list of all files that should be present in the  Quick Edit
release set that includes the Quick Edit application:

Quick Edit ReadMe

Mops Glossary

QEconsole

Stack Notation

Subject Glossary  (a folder)
    Arithmetic
    Compiler
    Console
    Control Structures
    Events
    Floating Point
    Memory
    OOP
    QuickDraw
    Stack
    Strings
    System
    Toolbox